<?php

/**
 * Storage server. 
 * 
 */
interface Ext_Storage_Interface
{

    /**
     * Used to login to the storage.
     *
     * @param   string  $user
     * @param   string  $pass
     * @return  mixed   $sid    the session Id or an Ext_Error.
     */
    public function login( $user, $pass );

    /**
     * Add user to the storage.
     *
     * @param   string  $sid
     * @param   string  $user
     * @param   string  $pass
     * @param   mixed   $role       Role (or an array of roles) to add.
     * @return  mixed   $error      true or an Ext_Error.
     */
    public function addUser( $sid, $user, $pass, $role );

    /**
     * Set user role.
     *
     * @param   string  $sid
     * @param   string  $user
     * @param   mixed   $role
     * @return  mixed   $error      true or an Ext_Error.
     */
    public function setUserRole( $sid, $user, $role );

    /**
     * Change user password.
     *
     * @param   string  $sid
     * @param   string  $user
     * @param   string  $pass
     * @return  mixed   $error      true or an Ext_Error.
     */
    public function changePassword( $sid, $user, $pass );

    /**
     * Del user from the storage.
     *
     * @param   string  $sid
     * @param   string  $user
     * @return  mixed   $error      true or an Ext_Error.
     */
    public function delUser( $sid, $user );

    /**
     * Get the user Id.
     *
     * @param   string  $sid
     * @param   string  $user
     * @return  mixed   $error      userId or an Ext_Error.
     */
    public function getUserId( $sid, $user );

    /**
     * Add user property.
     *
     * @param   string  $sid
     * @param   string  $user
     * @param   string  $propertyName
     * @param   string  $propertyValue
     * @return  mixed   $error      true or an Ext_Error.
     */
    public function setUserProp( $sid, $user, $propertyName, $propertyValue );

    /**
     * Add user property.
     *
     * @param   string  $sid
     * @param   string  $user
     * @param   string  $propertyName
     * @return  mixed   $propertyValue  value or an Ext_Error.
     */
    public function getUserProp( $sid, $user, $propertyName );

    /**
     * Open the file or create an entry representing this file if not exists.
     *
     * @param   string  $sid        the session Id is stored (somehow) into the fileId.
     * @param   string  $name 
     * @param   string  $owner 
     * @return  mixed   $fileId     the file Id or an Ext_Error.
     */
    function fileOpen( $sid, $name, $owner );

    /**
     * Store the file contents asyncronously.
     *
     * @param   mixed       $fileId         file id.
     * @param   string      $fileUrl        source url.
     * @param   string      $md5            file md5 for consistency checking.
     * @param   string      $callbackUrl    an url to call when transfer finished.
     * @param   array       $callbackData   user data to pass to callback 
     * @return  mixed       $error          true or an Ext_Error.
     */
    function asyncStore( $fileId, $fileUrl, $md5, $callbackUrl, $callbackData );

    /**
     * Retrieve the file contents asyncronously.
     *
     * @param   mixed       $fileId         file id.
     * @return  mixed       $error          true or an Ext_Error.
     */
    function asyncRetrieve( $fileId );

    /**
     * Store the file contents syncronously.
     *
     * @param   mixed       $fileId         file id.
     * @param   string      $buffer         file contents.
     * @return  mixed       $error          true or an Ext_Error.
     */
    function store( $fileId, $buffer );

    /**
     * Retrieve the file contents syncronously.
     *
     * @param   mixed       $fileId         file id.
     * @return  mixed       $buffer         the file contents or an Ext_Error.
     */
    function retrieve( $fileId );

    /**
     * Retrieve the file status.
     *
     * @param   mixed       $fileId         file id.
     * @return  mixed       $status         the file status: isEmpty, uploadPending, downloadPending, md5, size, name, owner
     */
    function getStatus( $fileId );

    /**
     * Set the file metadata.
     *
     * @param   mixed       $fileId         file id.
     * @param   array       $metadata       file metadata (user defined).
     * @return  mixed       $error          true or an Ext_Error.
     */
    function setMetadata( $fileId, $metadata );

    /**
     * Get the file metadata.
     *
     * @param   mixed       $fileId         file id.
     * @return  mixed       $metadata       file metadata (user defined array) or an Ext_Error.
     */
    function getMetadata( $fileId );

    /**
     * List the storage files.
     *
     * @param   string      $sid            the _session Id is stored (somehow) into the fileId.
     * @param   string      $owner          get some owner file list or all (if null).
     * @return  mixed       $fileList       array of files status: isEmpty, uploadPending, downloadPending, md5, size, name, owner
     */
    function listFiles( $sid, $owner );
}

